RichReader

A Word, HTML, and PDF Document Reader for the Palm Computing® Platform

Michael Arena
arenamj@erols.com

NOTE: The most recent documentation can always be found at the web site (it also has lots of screen shots!):
http://www.erols.com/arenakm/palm/RichReader.html

Introduction
RichReader is a document reader application for Palm Computing® Platform and Handspring handheld devices (such as the PalmPilot Pro, Palm III, Palm V, Visor, etc.). Unlike other document readers, the power of this program is its ability to display richly formatted text from any word processor/application (such as Microsoft® Word) that can create Rich Text Format (RTF) files or from downloaded Web pages in HTML files. Document readers display text documents that are stored on the handheld device.  RichReader can also read plain documents (without formatting codes) stored in standard AportisDoc™ format.  This format is efficient for platforms with limited memory.

If you are viewing this document on your handheld, you can already see the benefits that RichReader provides over standard plain text document readers. Words are displayed in various styles and sizes.  Paragraphs can be indented, justified, and have preceding bullets/numbers.  Not only do these highlights draw your eye to significant elements on the screen, but they also can improve comprehension of the author’s intent for certain words and phrases. For example (to borrow Sun’s catch phrase), if you read the sentence:

The Network Is The Computer™.

as plain text, it has a slightly different interpretation (to me) than when you read it as:

The Network Is The Computer™.

I developed this program to enhance your productivity while away from the desktop PC.  As a professional in the information age, you send and receive documents (probably Microsoft® Word or HTML documents) through email and can only view those documents while you are at your PC (or laptop). If you then need to bring that document to a meeting, you print it out, take it to the meeting, write notes and changes on the pages, bring it back to your desk, type in the notes, email the comments to the original author (or edit the original) document, and, finally, discard the paper that was only needed for a couple of hours.

Now you can streamline this process and go "paperless" at the same time. If you have a Document Reader such as RichReader on your handheld and desktop conversion software, you could save the Microsoft® Word document as rich text and convert it to a Palm file to be synched with the handheld. Then you will be able to read the formatted text and take notes in the Memo Pad.

RichReader Features
•	COLOR TEXT!
•	Recognizes foreground color attributes in HTML and RTF (not PDF yet). 
•	Color formatting is ignored on non-Palm IIIc devices.
•	Five different font styles:
Normal, Bold, Italic, Bold Italic, Fixed
All styles work with all font sizes (except there is no Small Bold).
•	Three different font sizes in proportional and fixed widths:
•	Small (<9 points) (7 pixels high, up to 22 lines per screen)
Normal, Bold, Italic, Bold Italic
Normal, Bold, Italic, Bold Italic
•	Medium (9-13 points) (11 pixels high, up to 14 lines per screen)
Normal, Bold, Italic, Bold Italic
Normal, Bold, Italic, Bold Italic
•	Large (14+ points) (14 pixels high, up to 11 lines per screen)
Normal, Bold, Italic, Bold Italic
Normal, Bold, Italic, Bold Italic
•	Solid underlining and dotted underlining (for links?). 
•	Three styles of paragraph justification:
Left justification is the most common.  Lines will wrap at 160 pixels which is the width of the Palm screen.
Centering for titles.
Right justification also works.
•	Long Word wrapping
Some lines that end in very long words can sometimes wrap after only a few characters in other programs:
This is an
extremely-long-nonsense-word-with-no-embedded-spaces.
But this seems wasteful so if the long word starts before about 58% of the width (95 pixels), then it will simply break the word like so:
This is an extremely-long-nonsense-word-with-no-embedded-spaces.
•	Horizontal lines:Œ
test
Œend test
•	Tables are displayed one cell at a time with a horizontal line at the start and end of each row and a horizontal line at the end of a cell.  Therefore, when viewing a table in RichReader, you can distinguish row boundaries by "thick" lines and cell boundaries by "thin" lines.
Product	Version	Price	
RichReader	1.61	$14.95	
RichWriter	?.??	$??.??	

•	Added the Euro symbol (€) at character 128 in the Small and Medium fonts (not the Large font).
•	Paragraph Indenting
This paragraph is left indented one inch.  The first line indent is set to zero so all lines are indented identically.
This paragraph is also left indented one inch but the first line is indented another one half inch relative to the left indent.
This last paragraph is also left indented one inch but the first line is negatively indented one half inch relative to the left indent.
•	Document information is saved between sessions
•	When a document is first opened, it is scanned for certain properties (this can take a while for large documents).  This information along with the current line number is saved in a database so that when leaving the application and then returning, the program will quickly return to where you left off.
•	Bookmarks
•	Bookmarks from a Microsoft® Word file will be added for:
•	Any "Heading" style (eg. Heading 2): the selected text will be bookmarked.
•	Bookmarks manually through the Insert -> Bookmark... menu.
•	A Table Of Contents (TOC): each item in the TOC will be bookmarked.
•	Bookmarks from an HTML file will be added for:
•	Header tags (<H1>, <H2>, <H3>, <H4>, <H5>, <H6>)
•	Anchor tags (<A NAME="abc"></A>).
•	Bookmarks saved by "another" Doc reader will also be scanned and added to the list.
•	Manually Add and Delete bookmarks
•	When Adding a bookmark, the first 15 characters of the top line of the screen are automatically copied to the Name: in the dialog.
•	Up to 200 bookmarks can be displayed.
•	Find
•	Allows you to search a document for a given string (up to 15 characters).
•	The line containing the matching string is displayed on the top line of the screen.
•	Case of letters are ignored (i.e. a = A)
•	All formatting is ignored
•	"Whitespace" characters are all considered equal.  You can enter a Space in the Find string and it will match a Space, Tab, Newline, or Carriage Return in the document
•	Wildcards!  The question mark (?) and period (.) characters in the Find string match any character in the document.
•	The search can be started from the Top of the document or from the Current Position.
•	Categories
•	Up to 30 user defined categories can be created.
•	When documents are first loaded they default to the Unfiled category.
•	Select a category from the Categories list to display only the documents within that category. NOTE: The All category will show all documents in all categories.
•	Select Edit Categories... from the Categories list in order to Add, Rename, or Delete categories.
•	Tap the Category button to change the category of the currently selected document.
•	View document in a single font style/size
•	There are two options on the Command menu which allow you to view “plain” text documents with one of the many permutations of fonts.  You can also “force” a “rich” document to be displayed in a single font/style (although why would you want to ;-).  
•	First, choose the Select Font menu item from the Command menu.  This brings up a screen that displays the entire font character set.  You can change the font size (Small, Medium, or Large) and set any combination of Bold, Italic, Underline, Fixed, and/or Link.
•	Then Close this screen (through the menu button).
•	Next, select a document in the Main screen, tap the Menu button and then choose the View with Selected Font item from the commands window.
•	NOTE: Currently, every time you choose View with Selected Font, this will recalculate the document formatting (even if it had been done previously) which means it could take a while for large documents and you will lose all manually added bookmarks.  However, if you keep the document open, switch to another application, then switch back to RichReader, then no recalculation will be done.  If you use the normal View command you don’t have to worry about this.
•	Rotate the screen
•	You can rotate the document View screen 90° Clockwise (CW) or Counter-Clockwise (CCW).  See the description of Preferences below.
•	The Main screen and all pop up dialogs and menus will not be rotated.
•	Document information is saved between sessions
•	When a document is first opened, it is scanned for certain properties. This information along with the current line number and bookmarks is saved in a database so that when leaving the application and then returning, the program will quickly return to where you left off.
•	Linux Converters
•	The command-line programs RTF2Doc and HTML2Doc have been ported to Linux.
•	Send me an email if you would like this distribution.
•	Large and Small View Controls (see Preference screen):
•	Use Large Controls for bigger buttons, icons, and scrollbar.
•	Use Small Controls to fit more lines of text on the screen

Operation
RichReader accomplishes the above features by using embedded formatting characters in the text and by using bitmap fonts to supplement the built in fonts of the handheld device.  The formatting characters are embedded using the command-line program RTF2Doc or the Windows program WRTF2Doc which will read a Rich Text Format .rtf file or using the command-line program HTML2Doc for reading .html files. These programs convert the documents into compressed AportisDoc™ format .pdb files with embedded formatting.  In order for these programs to run (as described in the included Install.txt file) you must modify/add two Environment Variables in the file C:\AUTOEXEC.BAT before running either program.

RTF2Doc, WRTF2Doc
Assuming that you have installed the contents of the ZIP file into the directory C:\RichReader, then add the following two lines at the end of the AUTOEXEC.BAT file:
set PATH=%PATH%;C:\RichReader
set RTFLIBDIR=C:\RichReader
From the MS-DOS console window, you can run RTF2Doc.exe:
Example: Assuming that you have created an RTF file from your word processor (MyDoc.rtf), then (at the DOS prompt) type (everything after the C:\> prompt):
C:\>RTF2Doc MyDoc.rtf
Input RTF file:     MyDoc.rtf: 30.5 kb
Temporary TXT file: MyDoc.txt: 21.5 kb
Output PDB file:    MyDoc.pdb: 11.4 kb

This will create an output file in the same directory called MyDoc.pdb with the title "MyDoc".

You can also manually specify a title (which appears in the Main window in RichReader):
C:\>RTF2Doc C:\Documents\MyDoc.rtf "My Document"
Input RTF file:     C:\Documents\MyDoc.rtf: 30.5 kb
Temporary TXT file: C:\Documents\MyDoc.txt: 21.5 kb
Output PDB file:    C:\Documents\MyDoc.pdb: 11.4 kb
This will create an output file in the directory C:\Documents called MyDoc.pdb with the title "My Document".  NOTE: It is important to enclose the entire title in double quotes (").

You can also have RTF2Doc automatically install the output file in your HotSync directory and set the registry flag for the HotSync operation by using the “-i”  option:
C:\>RTF2Doc -i MyDoc.rtf “MyDoc”
Input RTF file:     MyDoc.rtf: 30.5 kb
Temporary TXT file: MyDoc.txt: 21.5 kb
Output PDB file:    C:\pilot\ArenaM\Install\MyDoc.pdb: 11.4 kb
Installing file for HotSync user: Michael Arena

The Windows program WRTF2Doc.exe is in its first release.  It is a simple dialog application which prompts for a file name (using a standard file explorer dialog).  It will automatically format the output filename (.pdb) and set the title to the base filename (without the path and extension).  Then, you can change the title if you wish.  Then hit the Convert button.  After a brief pause (sorry, no progress indicator yet), a results dialog will pop up which shows the sizes of the input, output, (and temporary text) files so you can see the results of the compression (and how verbose RTF format is!)
NOTE: WRTF2Doc.exe was built using Visual C++ 6.0 which means you will need two Microsoft libraries (Mfc42.dll and Msvcrt.dll) to be installed in the directory C:\Windows\System (or in C:\Winnt\System32 if on Windows NT).  If these files do not already exist on your system, then send me an email and I will send you the DLL’s.

HTML2Doc
The console program HTML2Doc.exe is very similar to RTF2Doc.exe.  You specify the input HTML file, a title, and optionally the “-i” flag for automatic installation of the output file for HotSync:
C:\>HTML2Doc -i MyDoc.html “MyDoc”
Input HTML file:    MyDoc.html: 30.5 kb
Temporary TXT file: MyDoc.txt: 21.5 kb
Output PDB file:    C:\pilot\ArenaM\Install\MyDoc.pdb: 11.4 kb
Installing file for HotSync user: Michael Arena

RichReader
Once the document has been synched to the handheld, it will be displayed in RichReader’s Main screen.  Select the document you wish to view from the list (scroll the list if necessary).  The date the document was loaded is displayed along with its size in kilobytes.  Select the View button to view the document in the View screen.  The Main screen has two menus.  The Commands menus displays View, View with Selected Font, Select Font,  and Reinitialize.  View is identical to the View button.  Select Font displays a form which lets you examine a full character set in any of the sizes and styles listed above.  Reinitialize is used to discard saved information about documents and fonts.  This information will automatically be recalculated when necessary.  The Options menu displays About, Preferences, and Register.  About displays the version of RichReader.  Use this number when registering.  Preferences displays a dialog where you can change the behavior of certain features of the program.  Currently, there are two options.  One is to set the behavior of tapping the screen in View mode.  A tap can either scroll one page (up or down) or one line (up or down).  The other is to set the Rotation of the screen when displaying a document.  Choose None for normal display.  Choose CW to rotate the screen Clockwise which means the hardware buttons will be in your right hand. Choose CCW to rotate the screen Counter-Clockwise which means the hardware buttons will be in your left hand (NOTE: The meaning of the PageUp and PageDown keys is reversed in this orientation).  Register displays a dialog where you enter the registration key.  Once the payment information has been received by me from PalmPilotGear HQ (which includes your HotSync username and RichReader version number), I will email you your registration key.  Unregistered versions of RichReader will only display about the first 8-9 screens of a document.  However, the unregistered version will allow you to view the entire RichReader Doc (RichReader.pdb) included with the distribution.
The View screen has two areas: the document window and the status/control window.  Use the Page Up and Page Down hardware buttons to scroll up and down the document window one page at a time.  The last/first line of the previous screen is preserved automatically.  Tapping in the upper half of the document window will move up the document one line.  Tapping in the lower half of the document window (except in the status/control area) will move down the document one line.
The status/control area contains a lot of information:
•	The CLOSE button will close the document and return to the Main window.  
•	The position of the current screen expressed as a percentage.
•	The solid left arrow behaves the same as the Page Up button which scrolls up one page.
•	The scroll bar that visually displays the position of the current screen within the document.  A “thumb” denotes the current position.  Tap a location within the scroll bar to move the “thumb”.
•	The solid right arrow behaves the same as the Page Down button which scrolls down one page.
•	The Find button (magnifying glass icon) to activate the Find function.
•	The Find Again button (small magnifying glass with forward arrow icon) to activate the Find Again function.
•	The Bookmark button (page with corner folded icon) to activate the Bookmark function.

Future Enhancements
The following enhancements are planned for the next several minor releases:
•	Bookmarks
•	In the future, auto-scanning for bookmarks using the <X> convention at the end of a document may be supported.

The following are some ideas for potential enhancements in future major releases.
•	Superscript and Subscript
•	Examples: 1st Place, xi = y2.
•	Links within a document
•	Tapping on a link could jump to an existing bookmark (anchor) within a document.
•	Annotations
•	Annotations would provide the ability to attach small notes to a document (analogous to writing notes in the margin).
•	Farther in the future, possibly add the ability (through a conduit) to have the annotations transferred back to the PC so that they could be incorporated back into the original document (manually).
•	Auto-conversion and synching
•	You could set up a directory on the PC such that any .rtf files which are saved in this directory will automatically get converted and sent to the handheld when synching (using a conduit to do all the work).  The only manual step is coping (or saving) the RTF file to the special directory.

I would welcome any other suggestions for enhancements or changes to existing features.

Acknowledgments
•	The RTF2Doc program is based on: 
RTF Tools, Release 1.10
6 April 1994 Paul DuBois dubois@primate.wisc.edu 
•	Almost the entire file makedoc7.cpp by Pat Beirne, Harold Bamford, and Rick Bram has been included in all of the conversion programs.
•	The decompression algorithm in RichReader was based on information from the CQ Codeworks: The Doc Format page by Rob Tillotson robt@debian.org: http://www.concentric.net/~N9mtb/cq/doc/format.html and from makedoc7.cpp (from above).
•	James Clark’s (jjc@jclark.com) SP package was used for HTML parsing.
•	The source for the HotSync install process in the conversion programs was from Mark Pierce.

RichReader Copyright © 1999 Michael Arena.  All rights reserved.
All other trademarks and registered trademarks are the sole property of their respective owners.
http://www.erols.com/arenakm/palm

See the license information in License.txt (or LicenseFreeware.txt for RichReader Freeware).